#%RAML 1.0 DataType
description: |
    A logchunk represents a contiguous sequence of lines in a logfile.
    Logs are not individually addressable in the data API; instead, they must be requested by line number range.
    In a strict REST sense, many logchunk resources will contain the same line.

    The chunk contents is represented as a single unicode string.
    This string is the concatenation of each newline terminated-line.

    Each log has a type, as identified by the "type" field of the corresponding :bb:rtype:`log`.
    While all logs are sequences of unicode lines, the type gives additional information fo interpreting the contents.
    The defined types are:

     * ``t`` -- text, a simple sequence of lines of text
     * ``s`` -- stdio, like text but with each line tagged with a stream
     * ``h`` -- HTML, represented as plain text
     * ``d`` -- Deleted, logchunks for this log have been deleted by the Janitor

    In the stream type, each line is prefixed by a character giving the stream type for that line.
    The types are ``i`` for input, ``o`` for stdout, ``e`` for stderr, and ``h`` for header.
    The first three correspond to normal UNIX standard streams, while the header stream contains metadata produced by Buildbot itself.

    The ``offset`` and ``limit`` parameters can be used to select the desired lines.
    These are specified as query parameters via the REST interface, or as arguments to the :py:meth:`~buildbot.data.connector.DataConnector.get` method in Python.
    The result will begin with line ``offset`` (so the resulting ``firstline`` will be equal to the given ``offset``), and will contain up to ``limit`` lines.

    Following example will get the first 100 lines of a log::

        from buildbot.data import resultspec
        first_100_lines = yield self.master.data.get(("logs", log['logid'], "contents"),
            resultSpec=resultspec.ResultSpec(limit=100))

    Following example will get the last 100 lines of a log::

        from buildbot.data import resultspec
        last_100_lines = yield self.master.data.get(("logs", log['logid'], "contents"),
            resultSpec=resultspec.ResultSpec(offset=log['num_lines']-100))

    .. note::

        There is no event for a new chunk. Instead, the log resource is updated when new chunks are added, with the new number of lines.
        Consumers can then request those lines, if desired.



    Update Methods
    --------------

    Log chunks are updated via :bb:rtype:`log`.


properties:
    content:
        description: content of the chunk
        type: string
    firstline:
        description: zero-based line number of the first line in this chunk
        type: integer
    logid:
        description: the ID of log containing this chunk
        type: integer
type: object
